INTRODUCTION
============

Large projects usually already have some type of mechanism for build
numbering, because keeping track of which build is the latest can be
very important information. However, even small hobby projects can
benefit from a self-maintaining build numbering system.

BuildNumber is a utility to add auto-incrementing build numbers to
C and C++ projects. BuildNumber will create and maintain a single 
header file called "buildnumber.h" for your project which you can 
#include to access the current build number. BuildNumber is written 
in pure C for maximum portability, but the binary can also be used 
with C++ projects, and the source should compile with almost any 
C/C++ compiler. 

Each time BuildNumber is run it will check in the current directory 
for the file "buildnumber.h". If it doesn't exist, it is created. If
it exists, the build number defined there is incremented.

The entire contents of a sample "buildnumber.h" are displayed below:

--------------------------------------------------------
  /* Generated by BuildNumber version 0.8 */
  
  #ifndef BUILD_NUMBER_H_ 
  #define BUILD_NUMBER_H_ 
  
  #define BUILDNUMBER 53
  #define BUILDNUMBER_STR "53"
  
  #endif /* BUILD_NUMBER_H_ */
--------------------------------------------------------

If the file exists, BUILDNUMBER and BUILDNUMBER_STR are both updated.
If it doesn't, they are initialized to 1 and "1". The maximum length
is 4 digits, so the build number can never exceed 9999 (if you're 
about to compile build 10,000 you need to reconsider your project's
direction). ;-) The minimum value is -999 (more on negative build
numbers below).

DO NOT EDIT THE "buildnumber.h" FILE DIRECTLY.
You may be tempted to edit this file, to manually change the build
number or maybe even add a custom #define or two, but don't do it. 
If BuildNumber detects a malformed file, the numbering sequence will
start over, which is probably not what you want. Deleting the file
causes it to be created and will also cause the build numbering to
start over. If you need a different beginning build number, e.g. if 
you would like to start with a 4-digit number such as "1001", you can 
pass the number as a command-line option; this action is described 
below in "USING BuildNumber".

Note that neither major nor minor versioning information is present.
Unlike build numbers which need and ought to be updated every build, 
versioning changes infrequently and is simple to define and update
when necessary. 

BuildNumber is licensed under the BSD License for maximum freedom, 
even in commercial projects. See LICENSE.TXT for full terms, a copy
of which must be included with the original or modified source and 
this README.TXT file. Although not part of the license, if you use 
BuildNumber, please let me know by sending an email to:
obijohn@users.sourceforge.net


USING BuildNumber
=================

The idea is to run BuildNumber every time you build your project, and
to do so as the first step of the build process. For gcc (whether in
mingw, cygwin, linux, *BSD, etc) this can be defined in the project's
Makefile. With MS Visual Studio, this can be defined in the Project 
Properties. See the example folders for sample Makefiles and a Visual
Studio project file for BuildNumber itself. Simply compiling a file
within your project will not cause the build number to increase, as 
this will not invoke the BuildNumber tool. Only when you execute make
(when the Makefile is set up to use BuildNumber) or when you select
"Build" in Visual Studio (either for a single project or an entire 
solution), or when you run BuildNumber directly on the command line, 
will it update the buildnumber.h file.

make (all platforms):
With Makefiles, it is easy to add BuildNumber to your project builds.
BuildNumber checks for and updates "buildnumber.h" in the current 
working directory, so when using the buildnumber command within a 
Makefile, the file will be created in the directory from which you
invoked the make command (which is not necessarily the same directory
the Makefile itself is in). For example, if your Makefile is in the
top-level directory of a project tree and all the source code is in 
a subdirectory, executing make in the top-level project directory 
will cause "buildnumber.h" to be created and updated in that same 
top-level directory. See the "examples" directory in the source
distribution for sample Makefiles which use BuildNumber. The Makefile
for BuildNumber itself is included in the root directory of the 
source distribution (please see the comments of the Makefile for more
information on building BuildNumber).

Visual Studio:
For a Microsoft Visual Studio project (2002 on up), you can assign a
Pre-Build Event in the Project Properties page and define a command 
line for the build event. Simply set the command line to point to
buildnumber.exe with it's full path. The "buildnumber.h" file will 
then be created and updated in your project folder. See the 
"examples" directory for a snapshot of a Project Properties page. A
project file for BuildNumber itself is included with the source. The
VS 2003 command-line tools are available as a free download, though
some additional (also free) downloads are usually neccessary to get
a full working compiler toolset, such as the Platform SDK. 
VCBUILD.EXE is the command needed to build directly from the project 
file. Debug and Release configurations are both present in the 
project file for BuildNumber itself. To build only the Release 
configuration, use the following command (making sure VCBUILD.EXE is
in your path): VCBUILD.EXE buildnumber.vcproj Release
The BuildNumber Visual Studio project file is located in the examples
subdirectory of the source distribution. Also see the examples 
subdirectory for sample VS project files which use BuildNumber, which
you can easily edit and adapt to your own projects.

Specifying a build number:
When used in an automated process (Makefile, batch file, Visual
Studio project, etc) the buildnumber command should usually be given
with no options. When used directly in a console, some standard 
options are recognized (e.g. --version, --help) as well as passing a
number as the option. This number is then used as the new build 
number when creating or updating "buildnumber.h". If the number is
larger than 9,999 it is capped and remains at 9,999 until 
"buildnumber.h" is deleted or it is reset with a lower number; if it 
is smaller than -999 it is set to -999. Note that when using negative
build numbers, successive builds will increment towards 0. This is 
the only way to actually have a build number of 0, since using 0 as
a command-line option is ignored. If the command-line option is not 
recognized (or if it is 0), it is ignored and the program executes as
if no command-line option was given, rather than exiting with an 
error (this behavior may change if future versions). 

BuildNumber can be used in almost any environment that allows for
inserting a step into the build process. Even if this is done with a
batch file or shell script or directly on the command line, as long 
as it is invoked as the first step for every build, you will have an 
auto-incrementing build numbering system at your disposal.


USING "buildnumber.h"
=====================

Within your source files, just #include "buildnumber.h"[*] when you 
need access to the current build number (for example, in response to
a "--version" command-line switch or in an "About" dialog).

For example:

  #include <iostream>
  #include "buildnumber.h"

  using namespace std;
  
  int main(int argc, char *argv[])
  {
    cout << "Hello Build " BUILDNUMBER_STR "!" << endl;
    cout << "The next Build will be " << (BUILDNUMBER + 1) << endl;
  }

[*]Because "buildnumber.h" is not necessarily in the same directory as
the rest of your source, you may need to specify it's relative path
(e.g. "../buildnumber.h"), or add the relative path to the list of 
default include directories in the compiler switches.

The above C++ example, with Makefile and Visual Studio project file, 
is included in the "examples/HelloBuild.cpp" subdirectory of the 
source distribution. Also see the examples directory for a C example, 
also with Makefile and Visual Studio project file.